Repository navigation
feat(runtime): extend the run result envelope for durable multi-step runs - #573
Merged
Merged
Conversation
…runs
Add additive, empty-defaulted fields so consumers with durable
multi-step runs can adopt the canonical envelope without loss:
- status_detail: opaque, consumer-defined raw status/reason preserved
verbatim alongside the canonical status.
- steps: per-step result records, normalized as a list of maps.
- parent_run_id / child_run_refs: parent/child run relationships for
fan-out, with child_run_refs normalized like artifact_refs.
normalize_status() no longer coerces unrecognised input to the active
'running' state. Exact enum matches still win; a recognisable terminal
prefix/suffix ('failed…', 'completed…', 'cancel…', 'skipped'/
'*_skipped') maps to that terminal value, and anything else maps to
'incomplete'. Empty/null input still maps to 'running', preserving the
existing behavior in-progress producers rely on when the envelope is
built before a terminal status is known. from_array() preserves the
raw status in status_detail whenever it wasn't an exact enum match and
no status_detail was explicitly supplied.
WP_Agent_Workflow_Run_Result::to_run_result_envelope() now also
projects its steps into the envelope's new top-level steps field (in
addition to the existing metadata.steps projection, kept for backward
compatibility).
SCHEMA and VERSION are unchanged; all new fields round-trip through
from_array()/to_array().
Fixes #571
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #571
Problem
WP_Agent_Run_Result_Envelopecouldn't model durable multi-step runs without loss: unrecognised statuses silently coerced to the activerunningstate, there was no field for per-step records, no status detail beyond the canonical enum, and no parent/child run relationships for fan-out.New fields (additive, empty defaults, appended at the end of the constructor)
status_detailstringstatus.stepsarray<int,array<string,mixed>>logs).parent_run_idstringchild_run_refsarray<int,array<string,mixed>>artifact_refs.SCHEMAandVERSIONare unchanged.from_array()/to_array()round-trip all four new fields; new getters (get_status_detail(),get_steps(),get_parent_run_id(),get_child_run_refs()) added.normalize_status()behavior changesucceeded)null/''runningrunning(preserved — see below)completed_no_itemsrunningcompletedfailed - timeoutrunningfailedagent_skippedrunningskippedcancel_requestedrunningcancelledquux)runningincompleteRule: exact enum match wins. Otherwise a recognisable terminal prefix/suffix (
failed…→failed,completed…→completed,cancel…→cancelled,skipped/*_skipped→skipped) maps to that terminal value; anything else maps toincomplete. Unknown input is never coerced torunning— that was the bug (a finished run with a domain-specific terminal status looked alive to any observer).Behavior change, called out per the issue's acceptance criteria: empty/null input is the one case still preserved as
running, matching the existing behavior for in-progress producers that build the envelope before a terminal status is known. I checked every current envelope producer insrc/(WP_Agent_Task_Run_Control,WP_Agent_Runtime_Package_Run_Result,WP_Agent_Workflow_Run_Result,WP_Agent_Package_Adoption_Result) and none of them currently pass an unrecognised non-empty status through to the envelope, so this is additive/dormant until a new consumer (e.g. Data Machine's durable multi-step runs) starts using it — no existing producer's observed behavior changes.from_array()also now setsstatus_detailto the raw status string whenever the raw value wasn't an exact enum match and nostatus_detailwas explicitly supplied in the input array, so the original domain status is never lost even when the caller didn't think to pass it explicitly.Workflow projection
WP_Agent_Workflow_Run_Result::to_run_result_envelope()already existed; it now also projectsstepsinto the envelope's new top-levelstepsfield (previouslystepsonly rode insidemetadata.steps, which is kept for backward compatibility with any existing reader).Docs
Grepped
docs/forrun-result/v1— the one reference (docs/channels-workflows-operations.md) only names the schema, it doesn't enumerate fields, so no doc changes were needed.Tests
Added to
tests/run-result-envelope-smoke.php:from_array()/to_array().normalize_status(): unknown →incomplete,completed_no_items→completed,failed - timeout→failed,agent_skipped→skipped,cancel_requested→cancelled,null/''→running(historical default preserved), every exact enum value unchanged.from_array(): raw status preserved verbatim instatus_detailonly when not an exact enum match; exact-match statuses don't synthesize astatus_detail.stepsinto the envelope's canonicalstepsfield.No existing test assertion changed behavior (there was no existing test asserting the unknown→
runningcoercion).Results
AI disclosure
AI assistance: Yes / Tool: OpenCode / Used for: implementation and tests